home *** CD-ROM | disk | FTP | other *** search
/ The Programmer Disk / The Programmer Disk (Microforum).iso / xpro / c3 / pro21 / source.doc < prev    next >
Encoding:
Text File  |  1992-10-13  |  95.1 KB  |  2,076 lines

  1.  
  2.  
  3.  
  4.  
  5.  
  6.  
  7.  
  8.  
  9.  
  10.  
  11.  
  12.  
  13.  
  14.  
  15.  
  16.  
  17.  
  18.  
  19.  
  20.  
  21.  
  22.  
  23.  
  24.  
  25.                                    SOURCE
  26.  
  27.  
  28.                                 Version 1.01
  29.  
  30.                               October 14, 1992
  31.  
  32.  
  33.                                  Written by
  34.  
  35.                                  Rick Maddy
  36.  
  37.  
  38.  
  39.  
  40.  
  41.  
  42.  
  43.  
  44.                           SOURCE Table of Contents
  45.  
  46.      1    Distribution . . . . . . . . . . . . . . . . . . . .  Page 1
  47.  
  48.      2    What is SOURCE?  . . . . . . . . . . . . . . . . . .  Page 1
  49.  
  50.      3    Quick Start  . . . . . . . . . . . . . . . . . . . .  Page 2
  51.  
  52.      4    The SOURCE Command Line  . . . . . . . . . . . . . .  Page 3
  53.           4.1  Global Options  . . . . . . . . . . . . . . . .  Page 3
  54.           4.2  Filenames . . . . . . . . . . . . . . . . . . .  Page 4
  55.           4.3  Local Options . . . . . . . . . . . . . . . . .  Page 5
  56.           4.4  Full Command Line . . . . . . . . . . . . . . .  Page 5
  57.  
  58.      5    SOURCE Options . . . . . . . . . . . . . . . . . . .  Page 5
  59.  
  60.      6    SOURCE.CFG . . . . . . . . . . . . . . . . . . . . . Page 16
  61.           6.1  SOURCE.CFG Location . . . . . . . . . . . . . . Page 16
  62.           6.2  Named Configuration Options . . . . . . . . . . Page 16
  63.           6.3  SOURCE.CFG Format . . . . . . . . . . . . . . . Page 17
  64.           6.4  Commenting SOURCE.CFG . . . . . . . . . . . . . Page 18
  65.           6.5  Modifying SOURCE.CFG  . . . . . . . . . . . . . Page 18
  66.  
  67.      7    SOURCE.PRT . . . . . . . . . . . . . . . . . . . . . Page 18
  68.           7.1  Default Printer . . . . . . . . . . . . . . . . Page 18
  69.           7.2  SOURCE.PRT Format . . . . . . . . . . . . . . . Page 19
  70.           7.3  Modifying Your Printer  . . . . . . . . . . . . Page 23
  71.  
  72.      8    SOURCE.LNG . . . . . . . . . . . . . . . . . . . . . Page 23
  73.           8.1  SOURCE.LNG Location . . . . . . . . . . . . . . Page 23
  74.           8.2  SOURCE.LNG Format . . . . . . . . . . . . . . . Page 24
  75.           8.3  Commenting SOURCE.LNG . . . . . . . . . . . . . Page 25
  76.           8.4  Defining Language Specific Features . . . . . . Page 25
  77.                8.4.1     Comments  . . . . . . . . . . . . . . Page 25
  78.                8.4.2     String and Character Literals . . . . Page 26
  79.                8.4.3     Blocks  . . . . . . . . . . . . . . . Page 27
  80.                8.4.4     Keywords  . . . . . . . . . . . . . . Page 28
  81.                8.4.5     Complete Definition . . . . . . . . . Page 28
  82.           8.5  General Points  . . . . . . . . . . . . . . . . Page 30
  83.  
  84.      9    Network Support  . . . . . . . . . . . . . . . . . . Page 30
  85.  
  86.      10   Definition of Shareware  . . . . . . . . . . . . . . Page 31
  87.  
  88.      11   Disclaimer - Agreement For Trying SOURCE . . . . . . Page 31
  89.  
  90.      12   Registering  . . . . . . . . . . . . . . . . . . . . Page 32
  91.  
  92.      13   Future Enhancements  . . . . . . . . . . . . . . . . Page 33
  93.  
  94.      14   Acknowledgements . . . . . . . . . . . . . . . . . . Page 33
  95.  
  96.      SOURCE REGISTRATION . . . . . . . . . . . . . . . . . . . Page 34
  97.  
  98.  
  99.  
  100.  
  101.  
  102.                                    Page i
  103.                                    SOURCE
  104.  
  105.      SOURCE Version 1.01 - Source code file printing utility
  106.      Copyright 1992 Rick Maddy
  107.  
  108.      1    Distribution
  109.  
  110.      The SOURCE program is made up of these files:
  111.  
  112.           SOURCE.EXE     The SOURCE program file.
  113.           SOURCE.DOC     This documentation file.
  114.           SOURCE.PRT     The default printer definition file.
  115.           SOURCE.CFG     The default configuration option file.
  116.           SOURCE.LNG     The default language definition file.
  117.           README.1ST     Quick summary and last minute notes.
  118.           REGISTER.TXT   Order form to register SOURCE.
  119.  
  120.      This unregistered shareware program is distributed in the PKZIP
  121.      format.  SOURCE.ZIP may be passed onto as many people as you
  122.      like, provided it remains intact, ALL files are kept together,
  123.      and only the original files are distributed.  DO NOT zip up and
  124.      pass on your modified files.  See section 10 below for further
  125.      information on shareware.
  126.  
  127.      2    What is SOURCE?
  128.  
  129.      SOURCE, in its most basic form, is a program for printing source
  130.      code and text files.  However, using SOURCE to its fullest
  131.      potential gives you an extremely powerful and flexible program
  132.      for printing source code and allows for numerous options for
  133.      formatting the output:
  134.  
  135.           - Custom page sizing
  136.           - Adjustable margins
  137.           - Page orientation (portrait or landscape) 
  138.           - Character pitch (pica, elite, or compressed)
  139.           - Number of columns per page
  140.           - User definable page header/footers
  141.           - Optional banner page before/after files
  142.           - Output may be redirected to any device or file
  143.           - Printing ranges may be specified, including starting
  144.             and/or ending line or page numbers
  145.           - Multiple files can be queued for printing   
  146.  
  147.      In addition to these basic printing options, SOURCE contains many
  148.      options specifically geared toward formatting source code (such
  149.      as C, Pascal, Fortran, dBase, or whatever you code in).  These
  150.      include:
  151.  
  152.           - User definable line and page numbering
  153.           - Comments in the source code may be printed as bold,
  154.             italic, or underlined  
  155.           - Keywords may be highlighted
  156.           - Code blocks grouped graphically
  157.           - Adjustable tab sizes for printing
  158.           - Configurable language support
  159.  
  160.  
  161.                                    Page 1
  162.                                    SOURCE
  163.  
  164.      These are just some of the powerful options available to you. 
  165.      Yet, SOURCE is very easy to use.  SOURCE only needs to know the
  166.      name of the file(s) you wish to print and it does the rest.  You
  167.      can use SOURCE right out of the box (so to speak).  
  168.  
  169.      For example:
  170.  
  171.      C:\> SOURCE kludge.c
  172.  
  173.      This would print your file to the default printer using the built
  174.      in defaults. 
  175.  
  176.      You may configure each option to suit your needs.  See section 5
  177.      for a complete list of all the options.  Besides the printing
  178.      options, SOURCE is extremely flexible in its ability to work with
  179.      almost any printer and most programming languages. 
  180.  
  181.      To facilitate this dynamic environment, SOURCE consists of an
  182.      executable (SOURCE.EXE) and three support files:
  183.  
  184.           SOURCE.PRT:    Contains all the printer definitions.
  185.           SOURCE.CFG:    Contains all the default options used by
  186.                          SOURCE to print your files.
  187.           SOURCE.LNG:    Contains all the language and filename
  188.                          extension specifications needed for comment
  189.                          and keyword highlighting and block grouping.
  190.  
  191.      By default, all four files that make up SOURCE are named
  192.      "SOURCE.???" where '???' is "EXE", "PRT", "CFG", and "LNG".  If
  193.      you prefer to use a different name, such as "SRC", instead of
  194.      "SOURCE", simply rename all four files to the same prefix. 
  195.      Example:
  196.  
  197.           C:\>ren source.* src.*
  198.  
  199.      This will result in all four files having the "SRC.???" name
  200.      instead of "SOURCE.???".  Anywhere in this documentation you are
  201.      to execute "SOURCE", enter "SRC" instead.  The only advantage to
  202.      this is to save on typing "SOURCE" all the time, noe you enter
  203.      "SRC".  You could even change all the names to "S" if you really
  204.      like terse, UNIX-like command names.
  205.  
  206.      3    Quick Start
  207.  
  208.      Before running SOURCE for the first time (as if you have read
  209.      this far without having already done so), make sure you have
  210.      placed SOURCE.EXE, SOURCE.PRT, SOURCE.LNG, and SOURCE.CFG all
  211.      within the same directory.  You may also wish to include this
  212.      directory in your path so that you can run SOURCE from anywhere
  213.      on your system.  If you need more information on PATHs, see your
  214.      DOS manual.
  215.  
  216.      The simplest way of running SOURCE is to type:
  217.  
  218.           SOURCE filename.ext
  219.  
  220.                                    Page 2
  221.                                    SOURCE
  222.  
  223.      "SOURCE" is the program SOURCE and "filename.ext" is the name of
  224.      the file you are going to print.  You may press the [Esc] key
  225.      anytime while a file is printing to abort SOURCE and stop the
  226.      current file from printing.  Remember, most printers have buffers
  227.      and the printing will probably not stop immediately.
  228.  
  229.      The first time you run SOURCE you will be asked to select your
  230.      default printer.  This printer should be the one connected to
  231.      printer port one, "LPT1:".  If you are using a different port,
  232.      see section 6 for information on changing the printer port used
  233.      by SOURCE.  The list of printers initially supported by SOURCE
  234.      contains printers which should cover most of the printers in use. 
  235.      Pick the printer that closest matches the one you have.  
  236.  
  237.           Note:  If none of the printers are like yours, select
  238.           the "Generic" printer for now.  You will still be able
  239.           to print files, you just won't be able to take full
  240.           advantage of SOURCE's strengths.  Later on you'll see
  241.           how to modify SOURCE.PRT to take full advantage of your
  242.           printer.  See section 7 for more information on printer
  243.           definitions.
  244.  
  245.      Typing "SOURCE" at the prompt with no options will give you a few
  246.      lines about the general command line syntax.  You may type
  247.      "SOURCE -?" to see a few screens showing the command line syntax,
  248.      what each option is, and the options' current defaults.  After
  249.      the options, you will be shown what printers, languages, and
  250.      named configuration options are defined in the SOURCE.PRT,
  251.      SOURCE.LNG, and SOURCE.CFG files. 
  252.  
  253.      4    The SOURCE Command Line
  254.  
  255.      SOURCE is a command line utility.  To run SOURCE, type the name
  256.      of this program, SOURCE, followed by any options you wish to use
  257.      along with the filename(s) of the file(s) you wish to print.  The
  258.      command line syntax is as follows:
  259.  
  260.      SOURCE [-global options] filename.ext [-local options] . . .
  261.  
  262.      Objects in square brackets are optional and the ". . ." means you
  263.      may repeat as many filenames as you wish to have printed.
  264.  
  265.      The command line has two levels of options, global and local. 
  266.      Global options are configuration options that apply to all files
  267.      on the command line.  Local options only apply to the files that
  268.      immediately precede them. 
  269.  
  270.      4.1  Global Options
  271.  
  272.      Global options appear after the program name and before the first
  273.      filename.  These options apply to all the files specified on the
  274.      command line.  Global parameters are optional.  The syntax of
  275.      global options is a hyphen ( - ) followed by a one letter option
  276.      followed by any required parameters.  Options that take
  277.      parameters require that there be no space between the option and
  278.  
  279.                                    Page 3
  280.                                    SOURCE
  281.  
  282.      the parameter.  String parameters are slightly different.  A
  283.      space before the parameter is allowed.  String parameters may
  284.      also be enclosed in double quotes.  The quotes are required only
  285.      if the string contains spaces.  An example is:
  286.  
  287.           SOURCE -n -N4 -r com1
  288.  
  289.      The above example only contains global options (in this case,
  290.      four digit line numbers with output redirected to comm port one).
  291.      This example will not actually produce any output because no
  292.      files are specified yet.
  293.  
  294.      Options that you use frequently can be permanently preset within
  295.      the SOURCE.CFG file.  This way, you do not have to specify them
  296.      each time you use SOURCE.  See section 6 for a discussion on
  297.      setting global options as defaults. 
  298.  
  299.      4.2  Filenames
  300.  
  301.      After the global parameters, if any, you may specify the files
  302.      you wish to print.  In the simplest form, this would be a single
  303.      filename and its extension.
  304.  
  305.           SOURCE foobar.c
  306.  
  307.      Running this would cause SOURCE to print the file "foobar.c" from
  308.      the current directory.  To specify a file in another directory or
  309.      on another disk drive, use the full path name, as in the example
  310.      below:
  311.  
  312.           SOURCE c:\src\code.pas
  313.  
  314.      This would print the file "code.pas" found in the "c:\src\code"
  315.      directory despite your current working directory.
  316.  
  317.      There are three methods for printing multiple files.  The most
  318.      tiresome is to run SOURCE once for each file you need to print.
  319.  
  320.      The second option is to use wildcards when specifying the
  321.      filename.  The wildcards allowed are '*' and '?'.  These behave
  322.      exactly like the wildcards used by DOS commands (such as copy and
  323.      delete).  If you do not understand how wildcards work, please
  324.      refer to your DOS manual for more information.  An example of
  325.      wildcard use is:
  326.  
  327.           SOURCE *.c
  328.  
  329.      This would cause SOURCE to print all files in the current
  330.      directory that had the extension ".c".  Each file will be printed
  331.      separately, starting on page one, line one.
  332.  
  333.      The third method for printing multiple files is to enter more
  334.      than one name on the command line:
  335.  
  336.           SOURCE program.c data.txt
  337.  
  338.                                    Page 4
  339.                                    SOURCE
  340.  
  341.      This would cause SOURCE to print the two files, "program.c" and
  342.      "data.txt", from the current directory.  You may specify as many
  343.      files as the command line has room for.
  344.  
  345.      Any combination of these methods may used, for example:
  346.  
  347.           SOURCE *.c b:*.txt c:\proj\*.*
  348.  
  349.      This command line would print all 'C' files in the current
  350.      directory, all files with the extension ".txt" from the disk in
  351.      the B drive, and all files from the "proj" directory of the C
  352.      drive.
  353.  
  354.      4.3  Local Options
  355.  
  356.           In addition to the global options, you may specify "local"
  357.      options after each filename.  These local options override the
  358.      global options and only apply to the file they immediately follow
  359.      on the command line.  Local options are optional.  The syntax for
  360.      local options is identical to that of global options (see section
  361.      4.1).  Example:
  362.  
  363.           SOURCE -n hello.c goodbye.c -n-
  364.  
  365.      This command will cause SOURCE to print the file "hello.c" from
  366.      the current directory with line numbers and "goodbye.c" without
  367.      line numbers.  The global option "-n" causes line numbering to be
  368.      turned on for all files.  Specifying "-n-" after "goodbye.c"
  369.      tells SOURCE to turn line numbering off only for "goodbye.c" and
  370.      does not affect "hello.c".  Local options used after filenames
  371.      with wildcards will apply to all the files matched by the
  372.      wildcards:
  373.  
  374.           SOURCE *.c -b -c
  375.  
  376.      will print all 'C' files with block tracing and highlighted
  377.      comments turned on for each file.  This also shows that you may
  378.      specify more than one local option per file.  Of course, you do
  379.      not have to specify any local options if they are not needed.
  380.  
  381.      4.4  Full Command Line
  382.  
  383.      The command line for SOURCE is very flexible.  This flexibility
  384.      can also lead to some pretty long and complicated command lines. 
  385.      There are many ways to remedy this.  See section 6 for ways to
  386.      minimize the command line options.  The most complex command line
  387.      would be as follows:
  388.  
  389.           SOURCE -n -N4 file.pas -c -b *.c -h2 *.dat -n-
  390.  
  391.      This line contains global options and three file specifications
  392.      each giving their own local options.  You will not normally have
  393.      such lines, but the power is there to use.
  394.  
  395.      5    SOURCE Options
  396.  
  397.                                    Page 5
  398.                                    SOURCE
  399.  
  400.      What follows is a list of all the command line options that
  401.      SOURCE recognizes.  These options may be specified as global or
  402.      local options on the command line (unless indicated otherwise). 
  403.      They may also appear in the SOURCE.CFG file to define default
  404.      options for those options you wish to have in effect each time
  405.      you run SOURCE.  See section 6 for more on the SOURCE.CFG file. 
  406.      All options are case sensitive so do not run SOURCE with your
  407.      caps lock on.
  408.  
  409.      Conventions used below:
  410.  
  411.           [x]       Square brackets indicate optional items.  There
  412.                     may not be a space between the option and the
  413.                     parameter if specified.  Example:
  414.  
  415.                     n[-] may entered as n or n-.
  416.  
  417.           {x|y}     Curly braces containing a list of choices
  418.                     separated with a vertical bar indicate that you
  419.                     must select one of the options available for that
  420.                     item.  There may not be a space between the option
  421.                     and the chosen parameter.  Example:
  422.  
  423.                     a{a|o|r} allows aa, ao, or ar.
  424.  
  425.           "text"    Quotes indicate that you must enter a text string. 
  426.                     You do not have to type the double quotes unless
  427.                     the string contains spaces.  There may be a space
  428.                     between the option and the string.  Example:
  429.  
  430.                     z "list" allows:
  431.                          z.exe.obj      <== No spaces
  432.                          z".exe.obj"    <== Quotes optional, no spaces
  433.                          z".exe .obj"   <==Quotes required, spaces
  434.                          z .exe.obj
  435.                          z ".exe.obj"
  436.                          z ".exe .obj"
  437.  
  438.                     Not allowed would be:
  439.  
  440.                          z .exe .obj
  441.  
  442.                     because the parameter contains a space and must be
  443.                     enclosed in quotes.
  444.  
  445.           #         A pound symbol indicates that you must enter a
  446.                     number after the option.  Numbers may be made up
  447.                     of the 10 numeric digits and minus for negative
  448.                     numbers.  There may not be a space between the
  449.                     option and the number.  Example:
  450.  
  451.                     w# allows w1, w2, w3, etc.
  452.                     h# allows h-1, h2, h0, etc.
  453.  
  454.  
  455.  
  456.                                    Page 6
  457.                                    SOURCE
  458.  
  459.      Option         Description
  460.  
  461.      ?              Help.  The '?' option displays a quick command
  462.                     summary showing all the available options and
  463.                     their current defaults.  Running SOURCE with no
  464.                     options simply shows the command line syntax and
  465.                     the '-?' option.
  466.  
  467.      a{a|o|r}       Append/Overwrite.  The 'a' option describes the
  468.                     action SOURCE will take when redirecting the
  469.                     output to a file and the file already exists.  See
  470.                     the 'r' option for more on redirecting the output. 
  471.                     When the 'a' option is followed by an 'a', SOURCE
  472.                     will automatically append the new output to the
  473.                     previous contents of the file.  When followed by
  474.                     an 'o', SOURCE will automatically overwrite the
  475.                     old contents of the file and leave only the new
  476.                     output.  When followed by an 'r', SOURCE will
  477.                     interactively prompt you for the action to take. 
  478.                     You may specify 'append', 'overwrite', enter a
  479.                     different file, or quit SOURCE.  Default is 'ar',
  480.                     request.
  481.  
  482.      b[-]           Block Grouping.  The 'b' option sets whether block
  483.                     grouping is turned on or not.  The 'b' may be
  484.                     followed by '-'.  The 'b' option alone turns on
  485.                     block grouping, the minus turns it off.  For this
  486.                     option to work, SOURCE must know what language the
  487.                     file is written in.  This is done by using the
  488.                     filename extension as defined in the SOURCE.LNG
  489.                     file or the 'x' option may be used to force a
  490.                     specific language.  The lines used for block
  491.                     grouping may be drawn using either standard ASCII
  492.                     characters or the IBM line drawing characters. 
  493.                     See the 'g' option to set how the lines are drawn. 
  494.                     Default is 'b', block grouping on.
  495.  
  496.                     Below is some sample C code with block grouping
  497.                     turned on:
  498.  
  499.                          while (x < 10)
  500.                               ┌{
  501.                               │if (a < b)
  502.                               │    ┌{
  503.                               │    │puts("Hello");
  504.                               │    └}
  505.                               │else
  506.                               │    ┌{
  507.                               │    │puts("Goodbye");
  508.                               │    └}
  509.                               │x++;
  510.                               └}
  511.  
  512.  
  513.  
  514.  
  515.                                    Page 7
  516.                                    SOURCE
  517.  
  518.                     The above also assumes the 'g' option is on.  With
  519.                     the 'g' option off, the same code looks as
  520.                     follows:
  521.  
  522.                          while (x < 10)
  523.                               +{
  524.                               |if (a < b)
  525.                               |    +{
  526.                               |    |puts("Hello");
  527.                               |    +}
  528.                               |else
  529.                               |    +{
  530.                               |    |puts("Goodbye");
  531.                               |    +}
  532.                               |x++;
  533.                               +}
  534.  
  535.      B#             Banner.  The 'B' option allows you to print a
  536.                     banner before and/or after each file.  The banner
  537.                     contains the filename and extension in BIG
  538.                     letters.  The 'B' must be followed by a number
  539.                     from 0 to 3.  0 means no banner at all.  1 means a
  540.                     banner only before the file.  2 means a banner
  541.                     only after the file.  3 means a banner before and
  542.                     after the file.  Default is 'B3', print banner
  543.                     before and after.
  544.  
  545.      c[-]           Comment Highlighting.  The 'c' option sets whether
  546.                     comments within your programming code are
  547.                     highlighted or not.  The 'c' may be followed by
  548.                     '-'.  The 'c' option alone turns on highlighting,
  549.                     the minus turns off it off.  For this option to
  550.                     work, SOURCE must know what language the file is
  551.                     written in.  This is done by using the filename
  552.                     extension as defined in the SOURCE.LNG file or the
  553.                     'x' option may be used to force a specific
  554.                     language.  The highlighting method used is as
  555.                     defined in the SOURCE.PRT file for the selected
  556.                     pitch.  Default is 'c', highlighted comments on.
  557.  
  558.      d "printer"    Select Printer.  The 'd' option specifies which
  559.                     printer definition in the SOURCE.PRT file SOURCE
  560.                     should use when printing out files.  The 'd' must
  561.                     be followed by the printer name.  The name
  562.                     specified is not case sensitive.  If you only have
  563.                     one printer connected to your computer you will
  564.                     not need to use this option.
  565.  
  566.                     If you have multiple printers connected to
  567.                     different ports, you can specify this option at
  568.                     the command line when you are using a printer
  569.                     other than the default.  If this is the case, you
  570.                     will also need to use the 'r' option to specify
  571.                     the port the printer is connected to.  If you use
  572.                     different printers often, you may wish to define a
  573.  
  574.                                    Page 8
  575.                                    SOURCE
  576.  
  577.                     named configuration in the SOURCE.CFG file for
  578.                     each printer.  Then all you need to specify on the
  579.                     command line is the 'u' option.  See the 'u'
  580.                     option for more details on using named
  581.                     configurations.  The default printer is selected
  582.                     by the user the first time SOURCE is run or by
  583.                     modifying the SOURCE.PRT file.  See section 7 for
  584.                     more on SOURCE.PRT.
  585.  
  586.      e[-]           Escape Codes.  The 'e' option sets whether printer
  587.                     escape codes are output along with your text or
  588.                     not.  Normally you would want this left on so your
  589.                     printer will print the file properly.  Turning
  590.                     this option off would typically be used when
  591.                     redirecting output to a file when you would not
  592.                     want the escape codes embedded in the target file. 
  593.                     The 'e' may be followed by '-'.  The 'e' option
  594.                     alone causes the codes to be printed, the minus
  595.                     prevents the codes.  Default is 'e', codes
  596.                     printed.
  597.  
  598.      f#             Final Line.  The 'f' option allows you to specify
  599.                     the final line number of the file to print out. 
  600.                     This would be used to print only a desired block
  601.                     of code instead of having to print the entire
  602.                     file.  The 'f' must be followed by a positive
  603.                     number.  Specifying zero means the last physical
  604.                     line.  This option may not be used with the 'F' or
  605.                     'I' options unless set to zero.  Default is 'f0',
  606.                     print through last line.
  607.  
  608.      F#             Final Page.  The 'F' option allows you to specify
  609.                     the number of the final page of the file to print
  610.                     out.  This would be used to print only a block of
  611.                     code, or part of a page range, instead of printing
  612.                     out the entire file.  The 'F' must be followed by
  613.                     a positive number.  Specifying zero means the last
  614.                     physical page.  This option may not be used with
  615.                     the 'f' or 'i' options unless set to zero. 
  616.                     Default is 'F0', print through last page.
  617.  
  618.      g[-]           Graphics.  The 'g' option determines how the block
  619.                     group lines are printed (see option 'b' for more
  620.                     on block grouping).  When the option is on, the
  621.                     lines will be printed using the IBM line drawing
  622.                     characters.  With the option off, simple ASCII
  623.                     characters will be used.  If your printer cannot
  624.                     print the extended IBM character set then turn
  625.                     this off.  If your printer can print the lines
  626.                     then set this to on.  You may need to send a
  627.                     special code to your printer to select the IBM
  628.                     extended character set.  To do so, place the
  629.                     proper printer codes in the 'Init' record in the
  630.                     SOURCE.PRT file for your printer.  Default is
  631.                     'g-', print using standard ASCII.
  632.  
  633.                                    Page 9
  634.                                    SOURCE
  635.  
  636.      h#             Header Page.  The 'h' option is used to specify
  637.                     when to print the page header or footer.  The 'h'
  638.                     must be followed by a number.  Zero means no
  639.                     header or footer will be printed.  A one means to
  640.                     print the header only on the first page.  Any
  641.                     value of two or more will result in the header
  642.                     being printed on all pages.  To cause the header
  643.                     to be printed at the bottom of the page (now a
  644.                     footer), specify a negative number.  Negative one
  645.                     means to print a footer only on the first page. 
  646.                     Any number of -2 or less (-100 etc.) will cause
  647.                     the footer to be placed on all pages.  Page
  648.                     headers and footers are underlined and printed in
  649.                     10 pitch regardless of the pitch selected for the
  650.                     rest of the file.  The contents of the header are
  651.                     user definable by using the 'H' option.  Default
  652.                     is 'h2', header on all pages.
  653.  
  654.      H "header"     Header Definition.  The 'H' option is used to
  655.                     define the contents of the header or footer.  The
  656.                     definition consists of literal text and escape
  657.                     codes.  Since the definition will likely contain
  658.                     literal spaces, remember to enclose the definition
  659.                     within double quotes.  The escape commands are
  660.                     case sensitive and literal text will be shown as
  661.                     entered.  The escape sequences are described here:
  662.  
  663.                     &fn       Current filename and extension.  The
  664.                               filename is shown in uppercase.  No path
  665.                               is displayed.
  666.                     &fd#c     File creation date in specified format
  667.                               where # is 1 to 5 and c is the delimiter
  668.                               character ('/', ',', or '.').
  669.                     &ft#c     File creation time in specified format
  670.                               where # is 1 to 4 and c is the delimiter
  671.                               character (':', ',', or '.').
  672.                     &cd#c     Current date in specified format where #
  673.                               is 1 to 5 and c is the delimiter
  674.                               character ('/', ',', or '.').
  675.                     &ct#c     Current time in specified format where #
  676.                               is 1 to 4 and c is the delimiter
  677.                               character (':', ',', or '.').
  678.                     &pn#      Current page number in specified format
  679.                               where # is the number of digits the page
  680.                               number will take up.  The value must be
  681.                               in the range 1 to 9.  The page number
  682.                               will be left padded with spaces.  If you
  683.                               prefer zeros instead, precede the number
  684.                               with a zero.  Example:  &pn03.
  685.                     &li       Initial line number on page.
  686.                     &lf       Final line number on page.
  687.                     &h+       Turn on highlighting (using 10 high).
  688.                     &h-       Turn off highlighting (using 10 high).
  689.                     &jl       Left justify text.
  690.                     &jc       Center justify text.
  691.  
  692.                                   Page 10
  693.                                    SOURCE
  694.  
  695.                     &jr       Right justify text.
  696.                     &&        Prints a literal ampersand character.
  697.  
  698.                     Date formats:
  699.                     1)   mm dd yy       ex.  &fd1/     07/31/92
  700.                     2)   dd mm yy       ex.  &cd2.     31.07.92
  701.                     3)   yy mm dd       ex.  &cd3,     92,07,31
  702.                     4)   dd Mmm yy      ex.  &fd4-     31-Jul-92
  703.                     5)   Month dd  yyyy ex.  &cd5,     July 31, 1992
  704.  
  705.                     Time formats:
  706.                     1)   hh mm ss       ex.  &ct1:     15:45:21
  707.                     2)   hh mm          ex.  &ft2.     15.45
  708.                     3)   hh mm ss am    ex.  &ft3,     03,45,21 pm
  709.                     4)   hh mm am       ex.  &cd4:     03:45 pm
  710.  
  711.                     Example header definition:
  712.  
  713.                     '&h+File:&h-  &fn&jr&h+Page:&h-  &pn03'
  714.  
  715.                     This definition results in the following text:
  716.  
  717.                     File:  filename.ext                     Page:  001
  718.  
  719.                     where the text 'File:' and 'Page:' are
  720.                     highlighted, 'filename.ext' is the actual filename
  721.                     of the file, and the page number is right
  722.                     justified on the page.  Default is "File:  ",
  723.                     filename, file date, file time, "Printed:  ",
  724.                     date, time, "Page:  ", page number.
  725.  
  726.      i#             Initial Line.  The 'i' option allows you to
  727.                     specify the initial line number of the file to
  728.                     output.  This would be used to print only a block
  729.                     of code instead of the whole file.  The 'i' must
  730.                     be followed by a positive number.  Specifying zero
  731.                     means the first physical line.  It is likely that
  732.                     'i' would be used in conjunction with the 'f'
  733.                     option to print a specific range of text starting
  734.                     and finishing at the line numbers chosen.  This
  735.                     option may not be used with the 'F' or 'I' options
  736.                     unless set to zero.  Default is 'i0', the first
  737.                     line.
  738.  
  739.      I#             Initial Page.  The 'I' option allows you to
  740.                     specify the final page number of the file to
  741.                     output.  This would be used to print only a block
  742.                     of code instead of the whole file.  The 'I' must
  743.                     be followed by a positive number.  Specifying zero
  744.                     means the first physical page.  It is likely that
  745.                     'I' would be used in conjunction with the 'F'
  746.                     option to print a specific range of text starting
  747.                     and finishing at the page numbers chosen.  This
  748.                     option may not be used with the 'f' or 'i' options
  749.  
  750.  
  751.                                   Page 11
  752.                                    SOURCE
  753.  
  754.                     unless set to zero.  Default is 'I0', the first
  755.                     page.
  756.  
  757.      k[-]           Highlighted Keywords.  The 'k' option sets whether
  758.                     keywords within your programming code are
  759.                     highlighted or not.  The 'k' may be followed by
  760.                     '-'.  The 'k' option alone turns on highlighting,
  761.                     the minus turns it off.  Only those words listed
  762.                     in the "keyword" section of a language definition
  763.                     are highlighted.  For this option to work, SOURCE
  764.                     must know what language the file is written in. 
  765.                     This is done by using the filename extension as
  766.                     defined in the SOURCE.LNG file or the 'x' option
  767.                     may be used to force a specific language.  The
  768.                     highlighting method used is as defined in the
  769.                     SOURCE.PRT file for the selected pitch.  Default
  770.                     is 'k', highlighted keywords on.
  771.  
  772.      l{6|8}         Line Spacing.  The 'l' option specifies the number
  773.                     of lines per inch to print.  The 'l' must be
  774.                     followed by a 6 or an 8.  Ensure that the proper
  775.                     printer codes have been defined in the SOURCE.PRT
  776.                     file for the eight lines per inch option to work. 
  777.                     Default is 'l6', six lines per inch.
  778.  
  779.      m              Shareware Message.  The 'm' option causes a full
  780.                     screen message to display about registering
  781.                     SOURCE.  This command is only recognized if in
  782.                     SOURCE.CFG or as a global command line option.
  783.  
  784.      n[-]           Line Numbering.  The 'n' option is used to specify
  785.                     whether line numbers will be shown or not.  Line
  786.                     numbers are shown in the format specified in the
  787.                     'N' option.  The 'n' may be followed by '-'.  The
  788.                     'n' option alone turns on line numbering, the
  789.                     minus turns it off.  Default is 'n', line
  790.                     numbering on.
  791.  
  792.      N "beg#end"    Line Number Format.  The 'N' option specifies the
  793.                     size and format of line numbers.  The value of #
  794.                     must be a number between 1 and 9.  The terms "beg"
  795.                     and "end" represent literal text that may be shown
  796.                     before and after the line numbers.  For example,
  797.                     if you want four digit line numbers within square
  798.                     brackets, you would specify the option as 'N[4]'. 
  799.                     This would result in [   1], [   2], etc., being
  800.                     printed.  Another example would be if you wanted
  801.                     to specify 'N04:', which is the default, and this
  802.                     would result in the line numbers being printed as
  803.                     0001:, 0002:, and so on.  
  804.  
  805.                     The line numbers are left padded with spaces.  If
  806.                     you prefer the number to be left padded with
  807.                     zeros, precede the number with a zero.  For
  808.                     example:  'N4' will cause    1,    2, entering
  809.  
  810.                                   Page 12
  811.                                    SOURCE
  812.  
  813.                     'N04' will cause 0001, 0002, etc.  Both the
  814.                     'begin' and 'end' text are optional.  If there is
  815.                     no 'end' text, the source code will be adjacent to
  816.                     the line number.  To avoid this, you may wish to
  817.                     specify 'N"4 "'.  The space inside the double
  818.                     quotes will print after each line number.  
  819.  
  820.                     Specifying a value for the number of digits that
  821.                     is too small for the number of lines in the file
  822.                     to be printed will result in the line numbers
  823.                     wrapping around.  For example, if you specify N01
  824.                     and have 19 lines, line 10 would show up as 00,
  825.                     and line 11 would become 01.  This wrapping holds
  826.                     true for any size specified.  If your code
  827.                     typically has less than 1000 lines, specify 3 for
  828.                     the value of #, less than 10,000 lines, specify 4. 
  829.                     The default is 'N04:' which will produce 0001:,
  830.                     0002:, etc.
  831.  
  832.      o{l|p}         Page Orientation.  The 'o' option specifies the
  833.                     page orientation.  This will probably only work on
  834.                     laser printers since most dot matrix printers
  835.                     cannot print in landscape.  The 'o' must be
  836.                     followed by 'l' or 'p'.  The 'l' indicates
  837.                     landscape (sideways) printing and the 'p' is
  838.                     portrait (normal).  The landscape option requires
  839.                     that the 'landscape' field be filled in in the
  840.                     SOURCE.PRT file.  Default is 'op', portrait.
  841.  
  842.      p{p|e|c}       Pitch.  The 'p' option indicates the character
  843.                     pitch to print the files in.  The 'p' must be
  844.                     followed by 'p' (pica or 10 cpi), 'e' (elite or 12
  845.                     cpi), or 'c' (compressed using your printers
  846.                     compressed value, usually 15, 16.666, or 17).  If
  847.                     your printer allows large pitch sizes such as 5
  848.                     cpi, you could also use the compressed setting for
  849.                     this.  See section 7 for more on setting the
  850.                     compressed pitch value.  Default is 'pp', pica.
  851.  
  852.      q[-]           Page Count Query.  The 'q' option causes SOURCE to
  853.                     pre-scan each file and return the number of lines
  854.                     in the file and how many pages (excluding any
  855.                     banner pages) are required to print it based on
  856.                     all other print options.  You are then asked to
  857.                     confirm whether to print the file or not. 
  858.                     Pressing 'Y' or 'y' will cause the file to be
  859.                     printed.  Any other keystroke will prevent the
  860.                     file from being printed.  Pressing the [Esc] key
  861.                     will cause SOURCE to terminate.  The 'q' may be
  862.                     followed by '-'.  The 'q' option alone turns on
  863.                     the print statistics, the minus turns it off. 
  864.                     Turning on the 'q' option automatically turns on
  865.                     the 'v' (print verification) option.  Default is
  866.                     'q', show page count.
  867.  
  868.  
  869.                                   Page 13
  870.                                    SOURCE
  871.  
  872.      r "output"     Redirect.  The 'r' option allows you to redirect
  873.                     the output to a file or other device such as the
  874.                     screen or another printer port.  The 'r' must be
  875.                     followed by a filename or device name.  The file
  876.                     or device name is not case sensitive.  Example
  877.                     devices would be "LPT1", "PRN", or "COM2".  You
  878.                     may even specify "CON" to send the output to the
  879.                     screen.  When specifying a file, enter as much of
  880.                     the full path name as is needed.  You may specify
  881.                     another drive or directory.  No wildcards are
  882.                     allowed.  If the specified file already exists,
  883.                     SOURCE will act as specified by the 'a' option. 
  884.                     Default is 'r lpt1', output to printer port one.
  885.  
  886.      s{1|2}         Column Count.  The 's' option specifies the number
  887.                     of columns to print per page.  The 's' must be
  888.                     followed by a 1 or a 2.  It is recommended that
  889.                     compressed landscape printing be used with two
  890.                     columns.  Using two columns in 10 pitch, portrait
  891.                     print, leads to some difficult to read output. 
  892.                     Default is 's1', one column per page.
  893.  
  894.      S[-]           Show Column Separator.  The 'S' option is used in
  895.                     conjunction with the 's' option.  When you specify
  896.                     more than one column, the columns are separated by
  897.                     a vertical line.  The 'S' option allows you to
  898.                     tell SOURCE whether to display this vertical line
  899.                     or not.  The 'S' may be followed by '-'.  The 'S'
  900.                     alone turns the line on, the minus turns it off. 
  901.                     Default is 'S', line on.
  902.  
  903.      t#             Tab Stop Size.  The 't' option allows you to
  904.                     specify how many spaces a tab character should be
  905.                     printed as.  The 't' must be followed by a number
  906.                     from 0 to 8.  Specifying zero is equivalent to
  907.                     having all tabs removed from the file.  Default is
  908.                     't8', eight spaces per tab stop.
  909.  
  910.      u "name"       Use Named Configuration.  The 'u' option is used
  911.                     to specify a named configuration from within the
  912.                     SOURCE.CFG file.  See section 6.2 for more on
  913.                     named configurations.  The 'u' must be followed by
  914.                     a configuration name that has been defined in
  915.                     SOURCE.CFG.  The name is not case sensitive.  No
  916.                     default.
  917.  
  918.      v[-]           Print Verification.  The 'v' option is used to ask
  919.                     the user to confirm the printing of each file. 
  920.                     This would most likely be used in conjunction with
  921.                     wildcards in the filename.  For example, you want
  922.                     to print all but one or two files in a directory. 
  923.                     Specify "*.*/v" on the command line to select all
  924.                     the files.  SOURCE will then ask you to confirm
  925.                     the printing of each file.  Just press 'Y' or 'y'
  926.                     for the ones you want to print.  Any other key
  927.  
  928.                                   Page 14
  929.                                    SOURCE
  930.  
  931.                     stroke other than 'Y' or 'y' will be the same as
  932.                     no.  Pressing the [Esc] key will cause SOURCE to
  933.                     terminate.  The 'v' option is automatically turned
  934.                     on when the 'q' option is turned on.  The 'v'
  935.                     option may be followed by '-'.  The 'v' option
  936.                     alone turns on the print verify, the minus turns
  937.                     it off.  Default is 'v-', do not ask about each
  938.                     file.
  939.  
  940.      w#             Whitespace.  The 'w' option is used to specify the
  941.                     number of blank lines printed between the
  942.                     header/footer and the first/last line of text of
  943.                     the file on the page.  The 'w' must be followed by
  944.                     a value between 0 and 9.  Specifying zero will
  945.                     result in no blank space.  See the 'h' and 'H'
  946.                     options for more on user definable headers and
  947.                     footers.  Default is 'w1', one line.
  948.  
  949.      x "language"   Force Language.  The 'x' option allows you to tell
  950.                     SOURCE the language of a file regardless of its
  951.                     extension.  This option is useful only when using
  952.                     the 'b', 'c', or 'k' options (block grouping and
  953.                     comment or keyword highlighting).  The 'x' must be
  954.                     followed by a language name defined in SOURCE.LNG. 
  955.                     The name is not case sensitive.  For example, if
  956.                     you have a file with a 'bak' extension that really
  957.                     is a Pascal program, by following the file with
  958.                     the '-xPascal' option, SOURCE will treat the file
  959.                     as Pascal code so comments and blocks print
  960.                     correctly.  This assumes that there is a
  961.                     definition for 'Pascal' in the SOURCE.LNG file. 
  962.                     Default is none (use extension).
  963.  
  964.      y[-]           Sound.  The 'y' option determines whether the
  965.                     speaker will emit a bell or buzz sound when
  966.                     prompts or errors occur.  This option is not
  967.                     recognized as a local option.  The 'y' may be
  968.                     followed by '-'.  The 'y' option alone turns on
  969.                     sound, the minus turns them off.  Default is 'y-',
  970.                     sound off.
  971.  
  972.      z "list"       Ignore These Extensions.  The 'z' option is used
  973.                     to tell SOURCE what files to ignore during
  974.                     wildcard expansion.  For example, if you run
  975.                     SOURCE with "*.*", you will have a mess at your
  976.                     printer when it tries to print executables and
  977.                     object code!  You could specify the 'v' option
  978.                     each time and say no to files with ".exe" or
  979.                     ".obj" extensions, or you could use the 'z' option
  980.                     to tell SOURCE to automatically ignore the ".exe"
  981.                     and ".obj" extensions every time.  The syntax for
  982.                     the 'z' option is the list of extensions
  983.                     (including the period) between a pair of double
  984.                     quotes (if you place a space between each).  The
  985.                     list is not case sensitive.  To continue the
  986.  
  987.                                   Page 15
  988.                                    SOURCE
  989.  
  990.                     example, specify the 'z' option as 'z ".exe
  991.                     .obj"'.  You may specify as many extensions as you
  992.                     like as long as all are specified with one 'z'
  993.                     option.  Using two 'z' options will cause the
  994.                     first one to be ignored.  Default is 'z ".exe .com
  995.                     .sys .obj"'.
  996.  
  997.      6    SOURCE.CFG
  998.  
  999.      The SOURCE.CFG file is used to store groups of configuration
  1000.      options that may be used by SOURCE.  Among these groups are a set
  1001.      of default options.  These default options are seen by running
  1002.      SOURCE with the '-?' global option.  These default options, as
  1003.      initially defined, are actually the same defaults hard coded
  1004.      within SOURCE itself.
  1005.  
  1006.      6.1  SOURCE.CFG Location
  1007.  
  1008.      SOURCE.CFG is actually not needed.  If SOURCE can not find
  1009.      SOURCE.CFG, it will fall back on the built in defaults and
  1010.      continue to work fine.  SOURCE.CFG can be located in many
  1011.      different places.  By default, you should place a copy in the
  1012.      same directory as SOURCE.EXE (from now on referred to as the
  1013.      SOURCE directory).  With this setup, running SOURCE from any
  1014.      directory will cause SOURCE to use the defaults defined in
  1015.      SOURCE.CFG in the SOURCE directory.
  1016.  
  1017.      In addition to placing SOURCE.CFG in the SOURCE directory, you
  1018.      may also place other copies in any other directory you wish.  For
  1019.      example, you have a 'prog' directory on your hard disk.  If you
  1020.      place another copy of SOURCE.CFG in 'prog' and run SOURCE while
  1021.      your default directory is 'prog', SOURCE will use the SOURCE.CFG
  1022.      file in the 'prog' directory instead of the SOURCE directory.  By
  1023.      tailoring the SOURCE.CFG file to the files in 'prog', you can
  1024.      minimize the amount of command line options you need to specify. 
  1025.  
  1026.      The whole point to allowing this kind of flexibility is that you
  1027.      might be working on different projects that require different
  1028.      printing styles.  By placing tailored SOURCE.CFG files in the
  1029.      different directories, you can easily accomplish the diverse
  1030.      printing needs.
  1031.  
  1032.      6.2  Named Configuration Options
  1033.  
  1034.      If you have looked at the contents of SOURCE.CFG, you will notice
  1035.      that there seems to be more than just defaults defined in there. 
  1036.      SOURCE.CFG can actually store up to fifty sets of configuration
  1037.      options.  The first of which (as supplied) is the default
  1038.      options.  These different sets of options are referred to as
  1039.      named configuration options.  The supplied defaults are actually
  1040.      a named configuration option titled 'Default'.  SOURCE
  1041.      automatically looks for 'Default' and loads the options in if
  1042.      found.  In addition to the 'Default' setup, you may define 49
  1043.      more of your own design.  If for some reason you do not want the
  1044.      defaults loaded, rename 'Default' to something else.  You may
  1045.  
  1046.                                   Page 16
  1047.                                    SOURCE
  1048.  
  1049.      then refer to the defaults explicitly by using the 'u' option on
  1050.      the command line.  See section 5 for more information on
  1051.      selecting named configurations from the command line using the
  1052.      'u' option.
  1053.  
  1054.      The idea behind named configurations allows you to define a
  1055.      commonly used, but cumbersome, set of configuration options into
  1056.      a simple, single command line option.  A common use for them
  1057.      might be on a LAN where each user has their own favorite set of
  1058.      defaults.  The SOURCE.CFG file could contain one set for each
  1059.      user using their name or initials to name the options.  On the
  1060.      command line, simply specify "-u name" and all the options
  1061.      defined as "name" in SOURCE.CFG will be used.  Another
  1062.      circumstance could be to use named options when you are using
  1063.      SOURCE with multiple printers.  If you have "printer1" on "lpt1"
  1064.      and "printer2" on "com3", you could add two named configurations,
  1065.      "p1" and "p2".  "p1" would have '-d printer1 -r lpt1' and "p2"
  1066.      would have '-d printer2 -r com3'.  You could also add the 'g'
  1067.      option if one printer could print the IBM line drawing characters
  1068.      and one could not.  Typing 'source -u p1' at the command line is
  1069.      easier than 'source -d printer1 -r lpt1 -g'.  One other
  1070.      possibility would be if you wished to print source code in
  1071.      different languages in different formats.
  1072.  
  1073.      The named set of options may also contain a 'u' option.  This
  1074.      allows for nested definitions.  As an example, let's say you have
  1075.      two named configurations, "name1" and "name2".  If "name1"
  1076.      contains '-u name2', "name1" will pull in the options defined in
  1077.      "name2".  The result of using "name1" will be all the options in
  1078.      "name1" and all the options in "name2" being used.
  1079.  
  1080.      6.3  SOURCE.CFG Format
  1081.  
  1082.      The format of the SOURCE.CFG file is simple.  A named
  1083.      configuration begins with the key word "begin" followed by a
  1084.      name.  This name can contain any characters you can type at the
  1085.      DOS prompt.  I recommend descriptive names that indicate what the
  1086.      options represent.  Spaces are not allowed in the name.  The only
  1087.      limit is the full name must be 20 characters or less.  After the
  1088.      "begin" line, enter any set of options you like.  There are two
  1089.      ways of entering the options.  The easiest to read is to place
  1090.      one command per line.  Each command must be preceded by a hyphen. 
  1091.      Example:
  1092.  
  1093.      -t3
  1094.      -pp
  1095.  
  1096.      The second method allows more than one command per line.  This is
  1097.      identical to global options on the command line.  Simply separate
  1098.      the commands by at least one space.  Again, each command must be
  1099.      preceded by a hyphen.  Example:
  1100.  
  1101.      -l8  -s2
  1102.  
  1103.  
  1104.  
  1105.                                   Page 17
  1106.                                    SOURCE
  1107.  
  1108.      You may also enter the commands using any combination of the two
  1109.      methods.  Example:
  1110.  
  1111.      -q  -i5 -f100
  1112.      -z ".exe .obj .sys"
  1113.  
  1114.      After all options have been specified, enter the key word "end"
  1115.      on a line by itself to signal the end of the named definition. 
  1116.      You may define up to 20 named configurations.  A full definition
  1117.      would look as follows:
  1118.  
  1119.           begin Test
  1120.           -q -F2
  1121.           end
  1122.  
  1123.      6.4  Commenting SOURCE.CFG
  1124.  
  1125.      You may place comments in the SOURCE.CFG file by beginning a line
  1126.      with a semicolon ( ; ).  All text on that line will be ignored by
  1127.      SOURCE.  Do not place comments on lines with options.  The
  1128.      comment must go on a line by itself.  Example:
  1129.  
  1130.      ; This is a valid comment
  1131.      -b -c   ; This is not a valid comment - must be on own line
  1132.  
  1133.      6.5  Modifying SOURCE.CFG
  1134.  
  1135.      I recommend you modify the 'Default' named option in SOURCE.CFG
  1136.      to suit your most common needs.  This will result in having to
  1137.      specify little on the command line other than the filenames to
  1138.      print.  If you need to print a file slightly different one time,
  1139.      specify only the options required for the difference.  Add other
  1140.      named options for other commonly used configurations like those
  1141.      mentioned above.  This allows you to use very different print
  1142.      formats with minimal command line typing.
  1143.  
  1144.      One common change to the defaults would be to specify a different
  1145.      printer port.  Initially, SOURCE assumes printer port one, LPT1:. 
  1146.      If you are using a serial printer on a COM port or another
  1147.      printer port, change the default setting for the 'r' option. 
  1148.      Replace the word 'lpt1' with 'com1' or 'lpt2' or whatever is
  1149.      appropriate for you.
  1150.  
  1151.      7    SOURCE.PRT
  1152.  
  1153.      This file allows you to define any printer configuration you may
  1154.      have.  Only one copy of SOURCE.PRT is used and this must reside
  1155.      in the same directory as SOURCE.EXE.  This file is required and
  1156.      SOURCE will not run if not found.  SOURCE.PRT can contain printer
  1157.      definitions for up to 20 different printers, though I doubt you
  1158.      will ever need that many.  Once you define your printer, you can
  1159.      delete all other definitions if you like.  However, if you have
  1160.      more than one printer, leave all the necessary definitions.
  1161.  
  1162.      7.1  Default Printer
  1163.  
  1164.                                   Page 18
  1165.                                    SOURCE
  1166.  
  1167.      If you have more than one printer defined, you must make one the
  1168.      default.  This can be done automatically the first time you run
  1169.      SOURCE.  If you would like to change that default at a later
  1170.      time, you must manually edit the SOURCE.PRT file.  To make a
  1171.      printer the default, place the keyword "default" after the
  1172.      printer name.  Example:  'begin HPLJII+ default'.  If you specify
  1173.      more than one default, the last one will be chosen.  Remember you
  1174.      can use the 'd' option to select a printer other than the default
  1175.      if needed.  If you only have one printer defined in SOURCE.PRT
  1176.      you do not need to specify the keyword "default".
  1177.  
  1178.      7.2  SOURCE.PRT Format
  1179.  
  1180.      Similar to SOURCE.CFG, each definition in SOURCE.PRT begins with
  1181.      the keyword 'begin' followed by a name.  The name may be made up
  1182.      of any characters you can type at the DOS prompt up to 20
  1183.      characters.  The name may not contain spaces.  The printer
  1184.      definition ends with the keyword 'end' on a line by itself.  In
  1185.      between are the lines specifying your printer setup.  The syntax
  1186.      of each line is a field name, a colon, and the value you enter
  1187.      for that field.  Each line can contain only one field.  
  1188.  
  1189.      For those fields that require a printer escape sequence, you can
  1190.      enter the codes as literal characters or by entering the decimal
  1191.      value in square brackets.  You may also enter the code as a
  1192.      combination of both.  For example, the reset code on a Hewlett
  1193.      Packard Laser Jet is [Esc]E.  You might not be able to enter a
  1194.      literal escape character in your editor.  The solution is to use
  1195.      the decimal value in square brackets.  [Esc] is ASCII value 27. 
  1196.      The 'E' can be entered literally.  The two codes together would
  1197.      be entered into the reset field as:  [27]E.  Since the square
  1198.      brackets are being used as special characters by SOURCE, you may
  1199.      not enter them as literal characters in the printer code.  If
  1200.      your code needs the characters '[' or ']', enter the decimal
  1201.      value in square brackets.  The left bracket '[' becomes [91] and
  1202.      the right bracket ']' becomes [93].  The value inside the bracket
  1203.      must be a decimal number from 1 to 255.
  1204.  
  1205.      A list of the fields and a description of each is as follows:
  1206.  
  1207.      page width:    This field is the physical page width in inches. 
  1208.                     This will typically be 8.5 for standard letter
  1209.                     sized paper.  If you are using wide computer
  1210.                     paper, this could be 14.  This field is required.
  1211.  
  1212.      page length:   This field is the physical page length in inches. 
  1213.                     Normal letter size paper would be 11.  Legal size
  1214.                     paper would be 14.  This field is required.
  1215.  
  1216.      top margin:    Indicates the top margin in inches.  The first
  1217.                     printed line will be placed this far from the top
  1218.                     of the page.  A standard half inch margin would be
  1219.                     .5.  This value must be greater than or equal to
  1220.                     the top edge.  This field is required.
  1221.  
  1222.  
  1223.                                   Page 19
  1224.                                    SOURCE
  1225.  
  1226.      bottom margin: Indicates the bottom margin in inches.  The last
  1227.                     line printed will be this far from the bottom of
  1228.                     the page.  This value must be greater than or
  1229.                     equal to the bottom edge.  This field is required.
  1230.  
  1231.      left margin:   This is the left margin in inches.  The left most
  1232.                     characters will be this far from the left edge of
  1233.                     the paper.  This value must be greater than or
  1234.                     equal to the left edge.  This field is required.
  1235.  
  1236.      right margin:  This is the right margin in inches.  The right
  1237.                     most characters will be this far from the right
  1238.                     edge of the paper.  This value must be greater
  1239.                     than or equal to the right edge.  This field is
  1240.                     required.
  1241.  
  1242.      top edge:      The top edge is used to define the physical
  1243.                     limitation of the printer to print at the top of
  1244.                     the page.  Laser printers typically are set with a
  1245.                     half inch limit at the top.  By entering .5 here,
  1246.                     the margin specified in 'top margin' will come out
  1247.                     correctly.  This field is required.
  1248.  
  1249.      bottom edge:   The bottom edge is used to define the physical
  1250.                     limitation of the printer to print at the bottom
  1251.                     of the page.  Laser printers typically are set
  1252.                     with a half inch limit at the bottom.  By entering
  1253.                     .5 here, the margin specified in 'bottom margin'
  1254.                     will come out correctly.  This field is required.
  1255.  
  1256.      left edge:     The left edge is used to define the physical
  1257.                     limitation of the printer to print at the left
  1258.                     edge of the page.  Laser printers typically cannot
  1259.                     print on the first quarter inch of the left edge. 
  1260.                     By entering .25 here, the margin specified in
  1261.                     'left margin' will come out correctly.  The exact
  1262.                     value entered may be slightly different.  Try .2
  1263.                     or .3.  Experiment with the proper value to set
  1264.                     your printer up correctly.  This field is
  1265.                     required.
  1266.  
  1267.      right edge:    The right edge is used to define the physical
  1268.                     limitation of the printer to print at the right
  1269.                     edge of the page.  Laser printers typically cannot
  1270.                     print on the last quarter inch of the right edge. 
  1271.                     By entering .25 here, the margin specified in
  1272.                     'right margin' will come out correctly.  The exact
  1273.                     value entered may be slightly different.  Try .2
  1274.                     or .3.  Experiment with the proper value to set
  1275.                     your printer up correctly.  This field is
  1276.                     required.
  1277.  
  1278.      10 pitch:      This field is used to enter the escape sequence
  1279.                     used by your printer to print text at ten
  1280.  
  1281.  
  1282.                                   Page 20
  1283.                                    SOURCE
  1284.  
  1285.                     characters per inch.  Enter the sequence exactly
  1286.                     as shown in your printer manual including case.
  1287.  
  1288.      12 pitch:      This field is used to enter the escape sequence
  1289.                     used by your printer to print text at 12
  1290.                     characters per inch.  Enter the sequence exactly
  1291.                     as shown in your printer manual including case. 
  1292.                     This field is required to use this feature.
  1293.  
  1294.      compressed:    This field is used to enter the escape sequence
  1295.                     used by your printer to print text in compressed
  1296.                     mode.  This is usually 15, 16.66, or 17.  You may
  1297.                     even enter the code for enlarged print such as 5
  1298.                     cpi.  Enter the sequence exactly as shown in your
  1299.                     printer manual including case.  This field is
  1300.                     required to use this feature.
  1301.  
  1302.      comp size:     This field is used to specify the characters per
  1303.                     inch your printer will print while in compressed
  1304.                     mode.  Typically this value will be 15, 16.666, or
  1305.                     17 (or even 5 for enlarged print).  This field is
  1306.                     required to print in compressed mode.
  1307.  
  1308.      underline on:  This is the printer escape sequence for turning
  1309.                     underlining on.  This is used only by the page
  1310.                     header/footer.  This field is required to use this
  1311.                     feature.  If you do not want the header
  1312.                     underlined, leave this field blank.
  1313.  
  1314.      underline off: This is the printer escape sequence for turning
  1315.                     underlining off.  This is used only by the page
  1316.                     header/footer.  This field is required to use this
  1317.                     feature.  If you do not want the header
  1318.                     underlined, leave this field blank.
  1319.  
  1320.      10 high on:    This is the printer escape sequence used to print
  1321.                     comments when the 'c' option is used and the 'p'
  1322.                     option was set to 10.  This code could be almost
  1323.                     anything your printer can do.  Examples are bold,
  1324.                     underline, and italic.  DO NOT use a code that
  1325.                     prints in a different size font like expanded or
  1326.                     double height.  This will cause the file to print
  1327.                     incorrectly.  Whatever code is used must not
  1328.                     change the current print size.  This field is
  1329.                     required to use this feature.
  1330.  
  1331.      10 high off:   This is the printer escape sequence used to turn
  1332.                     off the code used by '10 high on'.  This field is
  1333.                     required to use this feature.
  1334.  
  1335.      12 high on:    This is the printer escape sequence used to print
  1336.                     comments when the 'c' option is used and the 'p'
  1337.                     option was set to 12.  This code could be almost
  1338.                     anything your printer can do.  Examples are bold,
  1339.                     underline, and italic.  DO NOT use a code that
  1340.  
  1341.                                   Page 21
  1342.                                    SOURCE
  1343.  
  1344.                     prints in a different size font like expanded or
  1345.                     double height.  This will cause the file to print
  1346.                     incorrectly.  What ever code is used must not
  1347.                     change the current print size.  This field is
  1348.                     required to use this feature.
  1349.  
  1350.      12 high off:   This is the printer escape sequence used to turn
  1351.                     off the code used by '12 high on'.  This field is
  1352.                     required to use this feature.
  1353.  
  1354.      comp high on:  This is the printer escape sequence used to print
  1355.                     comments when the 'c' option is used and the 'p'
  1356.                     option was set to your compressed value.  This
  1357.                     code could be almost anything your printer can do. 
  1358.                     Examples are bold, underline, and italic.  DO NOT
  1359.                     use a code that prints in a different size font
  1360.                     like expanded or double height.  This will cause
  1361.                     the file to print incorrectly.  What ever code is
  1362.                     used must not change the current print size.  This
  1363.                     field is required to use this feature.
  1364.  
  1365.      comp high off: This is the printer escape sequence used to turn
  1366.                     off the code used by 'comp high on'.  This field
  1367.                     is required to use this feature.
  1368.  
  1369.      init:          This code is sent to the printer before the first
  1370.                     file is printed.  This should contain all required
  1371.                     printer initialization codes to setup your
  1372.                     printer.  Examples would be the initialize printer
  1373.                     code, character set selection (not pitch size),
  1374.                     and print quality (draft, NLQ, etc.).  There
  1375.                     should be nothing in here for selecting pitch or
  1376.                     page orientation since this will be done using the
  1377.                     other codes specific to those settings.  This is
  1378.                     not required.
  1379.  
  1380.      reset:         This code is sent to the printer after the last
  1381.                     file is sent.  This can be blank.  This may be
  1382.                     used to place the printer back into the mode it
  1383.                     was prior to the "Init" code being sent.  This is
  1384.                     not required.
  1385.  
  1386.      portrait:      This is the code sent to the printer to set the
  1387.                     paper orientation to portrait - the usual way the
  1388.                     page is set.  This only applies to laser printers
  1389.                     since dot matrix printers cannot print any other
  1390.                     way using straight text printing (as opposed to
  1391.                     graphics).  This must be filled in if your printer
  1392.                     supports portrait and landscape printing.
  1393.  
  1394.      landscape:     This is the code sent to the printer to set the
  1395.                     paper orientation to landscape - sideways
  1396.                     printing.  This only applies to laser printers
  1397.                     since dot matrix printers cannot print landscape
  1398.  
  1399.  
  1400.                                   Page 22
  1401.                                    SOURCE
  1402.  
  1403.                     without using graphics.  This must be filled in to
  1404.                     make use of the landscape printing feature.
  1405.  
  1406.      6 lpi:         This code is used to print the file at six lines
  1407.                     per inch.  This is the usual default for all
  1408.                     printers.  If your printer does not support eight
  1409.                     lines per inch than you may leave this blank,
  1410.                     otherwise this is required.
  1411.  
  1412.      8 lpi:         This code is used to print the file at eight lines
  1413.                     per inch.  If your printer does not support eight
  1414.                     lines per inch than you may leave this blank,
  1415.                     otherwise this is required to use the feature.
  1416.  
  1417.      There are many relationships between the values placed in the
  1418.      above fields.  The sum of the top and bottom margins must be less
  1419.      than the page length.  The sum of the left and right margins must
  1420.      be less than the page width.  All margins must be greater than or
  1421.      equal to their corresponding edge.  If you only have 10 pitch
  1422.      printing, you may leave all three pitch codes blank.  If you can
  1423.      only print at six lines per inch, you may leave both the six and
  1424.      eight lines per inch codes blank.
  1425.  
  1426.      Certain combinations of print options do not work together on
  1427.      some printers.  For example, Hewlett Packard laser jet printers
  1428.      will not print bold or italic while in compressed print.  This is
  1429.      why there are separate highlight codes for the different pitch
  1430.      sizes.  This allows you to specify bold or italic for 10 and 12
  1431.      pitch and underlining for compressed printing.
  1432.  
  1433.      7.3  Modifying Your Printer
  1434.  
  1435.      As delivered, the SOURCE.PRT file has only a few basic printers
  1436.      within it.  These may not fit your printer completely if at all. 
  1437.      To take full advantage of your printer's abilities, you can edit
  1438.      SOURCE.PRT by placing an entry for your printer within it.  To do
  1439.      so, either reuse an existing entry that is similar to your
  1440.      printer or copy the 'Generic' definition and rename the copy to
  1441.      match your printer name.  Once you have this done, open up your
  1442.      printer's reference manual to the section that describes all the
  1443.      features and their associated escape sequences.  Enter the codes
  1444.      you need into the proper fields and you will be ready to go.  It
  1445.      may take some trial and error to get everything perfect, but it
  1446.      can be done.
  1447.  
  1448.      8    SOURCE.LNG
  1449.  
  1450.      SOURCE.LNG contains the definitions for the language support
  1451.      features of SOURCE.  The two options are comment highlighting and
  1452.      code block grouping or tracing.  The SOURCE.LNG file details what
  1453.      makes a comment, a literal string and character, and what
  1454.      represents a code block.
  1455.  
  1456.      8.1  SOURCE.LNG Location
  1457.  
  1458.  
  1459.                                   Page 23
  1460.                                    SOURCE
  1461.  
  1462.      SOURCE.LNG is not a required file.  If SOURCE can not find
  1463.      SOURCE.LNG, it will ignore the use of the b and c options and
  1464.      continue to work fine.  SOURCE.LNG can actually be located in
  1465.      many different places.  By default, you should place a copy in
  1466.      the same directory as SOURCE.EXE (from now on referred to as the
  1467.      SOURCE directory).  With this setup, running SOURCE from any
  1468.      directory will cause SOURCE to use the definitions in the
  1469.      SOURCE.LNG in the SOURCE directory.
  1470.  
  1471.      In addition to placing SOURCE.LNG in the SOURCE directory, you
  1472.      may also place other copies in any other directory you wish.  For
  1473.      example, you have a 'prog' directory on your hard disk.  If you
  1474.      place another copy of SOURCE.LNG in 'prog' and run SOURCE while
  1475.      your default directory is 'prog', SOURCE will use the SOURCE.LNG
  1476.      file in the 'prog' directory instead of the SOURCE directory.  By
  1477.      tailoring the SOURCE.LNG file to the files in 'prog', you can
  1478.      work with different dialects of the same language.
  1479.  
  1480.      The whole point to allowing this kind of flexibility is that you
  1481.      might be working on different projects that require different
  1482.      language definitions.  By placing tailored SOURCE.LNG files in
  1483.      the different directories, you can easily accomplish the diverse
  1484.      needs.
  1485.  
  1486.      8.2  SOURCE.LNG Format
  1487.  
  1488.      The format of SOURCE.LNG is similar to the other support files. 
  1489.      You begin a language definition with the keyword 'beginlang'
  1490.      followed first by the name of the language and then a list of
  1491.      filename extensions associated with the language.  The language
  1492.      name can be any characters you can type at the DOS prompt.  The
  1493.      name cannot contain spaces and may be up to 20 characters long. 
  1494.      The list of extensions are used to tell SOURCE to treat any file
  1495.      with the given extension as a file of that language.  An example
  1496.      would be:  'beginlang C .c .h'.  This defines a language called
  1497.      "C".  Any file with the extension ".c" or ".h" would be treated
  1498.      as a "C" file.  You may specify up to 10 extensions per language.
  1499.  
  1500.      The second line of the definition is a list of legal characters
  1501.      that may be found in identifiers and keywords.  Identifiers
  1502.      include variables and labels within a program.  These characters
  1503.      are used to tell SOURCE how to discern between to words in a
  1504.      program.  Most languages allow letter and numbers.  Some also
  1505.      allow some puncuation like underscores.  See your language
  1506.      reference.  It should detail the allowable characters.  The list
  1507.      of characters must be contiguous and on one line with no spaces. 
  1508.      You only need to specify either lower or upper case letters, not
  1509.      both.
  1510.  
  1511.      The language definition is completed with the keyword 'endlang'
  1512.      on a line by itself.  This may be followed by the keyword 'case'
  1513.      to indicate that the language is case sensitive and/or 'part' to
  1514.      indicate that keywords only need to match partially.  This is
  1515.      explained in detail below.  Any other keywords, or none at all,
  1516.      indicate that the language is case independent and keywords
  1517.  
  1518.                                   Page 24
  1519.                                    SOURCE
  1520.  
  1521.      require a full match.  Example:  'endlang case' terminates the
  1522.      language definition and specifies case dependency.  'endlang' or
  1523.      'endlang nocase' indicate the end of a case independent language.
  1524.  
  1525.      The SOURCE.LNG file may contain up to twenty language
  1526.      definitions.  You only need those for which you have use, so feel
  1527.      free to delete unneeded languages from the supplied SOURCE.LNG
  1528.      file.
  1529.  
  1530.      8.3  Commenting SOURCE.LNG
  1531.  
  1532.      You may place comments in the SOURCE.LNG file by beginning a line
  1533.      with a semicolon (;).  All text on that line will be ignored by
  1534.      SOURCE.  Do not place comments within a language definition, only
  1535.      before the 'beginlang' line or after the 'endlang' line.
  1536.  
  1537.      8.4  Defining Language Specific Features
  1538.  
  1539.      8.4.1  Comments
  1540.  
  1541.      After the 'beginlang' line, you specify how comments are defined. 
  1542.      This begins with the line ':comment:'.  After the ':comment:'
  1543.      line, you specify three lines.  The first line is the begin
  1544.      comment command, the second is the end comment command.  The
  1545.      third line contains a number from zero to 80.  This number
  1546.      indicates the column that the begin comment command must begin
  1547.      in.  A zero indicates that the comment may begin in any column. 
  1548.      An example for the 'C' language would be:
  1549.  
  1550.           :comment:
  1551.           /*                       <== Begin comment
  1552.           */                       <== End comment
  1553.           0                        <== Comment may be in any column
  1554.  
  1555.      You may specify more than one comment.  For example, Turbo Pascal
  1556.      allows the following:
  1557.  
  1558.           :comment:
  1559.           {
  1560.           }
  1561.           0
  1562.           (*
  1563.           *)
  1564.           0
  1565.  
  1566.      For languages such as BASIC where comments are terminated by the
  1567.      end of line, specify the begin command on the first line and
  1568.      leave the second line blank.  Example:
  1569.  
  1570.           :comment:
  1571.           REM
  1572.                                    <== This is a blank line
  1573.           0
  1574.  
  1575.  
  1576.  
  1577.                                   Page 25
  1578.                                    SOURCE
  1579.  
  1580.      One of the few examples of specifying a non-zero column number
  1581.      would be for FORTRAN.  Comments in FORTRAN are specified by
  1582.      placing a 'C' in column one.  The definition for this would be:
  1583.  
  1584.           :comment:
  1585.           C                        <== Comments begin with a C
  1586.                                    <== Terminated by end-of-line
  1587.           1                        <== C must be in column one
  1588.  
  1589.      Since blank lines are interpreted as part of the syntax, you may
  1590.      not leave blank lines within a language definition in the
  1591.      SOURCE.LNG file unless it is required as above.  You may define
  1592.      up to 7 comment marker pairs per language.
  1593.  
  1594.      8.4.2  String and Character Literals
  1595.  
  1596.      After defining the comments, you define what makes up literal
  1597.      strings and characters.  This is done just like comments.  You
  1598.      begin with the line ':string:'.  After this line, you enter two
  1599.      lines per string or character.  The first line contains the
  1600.      delimiter used to begin and end a literal string or character
  1601.      (typically a single or double quote).  The second line specifies
  1602.      an escape sequence.  This is the sequence (usually one character)
  1603.      used to allow the delimiter character to be used literally within
  1604.      a string or as a character.  'C' is a good example of this. 
  1605.      Strings are set in double quotes.  To place a double quote within
  1606.      a string, you must precede the double quote with a backslash ("He
  1607.      said \"Hello\"").  The definition would be as follows:
  1608.  
  1609.           :string:
  1610.           "                        <== String Delimiter
  1611.           \                        <== Escape Sequence
  1612.  
  1613.      Characters in 'C' are similar.  Literal characters are defined by
  1614.      single quotes.  To assign a literal single quote in 'C', you
  1615.      precede the literal quote with a backslash ('\'').  The
  1616.      definition would be:
  1617.  
  1618.           :string:
  1619.           '                        <== Character Delimiter
  1620.           \                        <== Escape Sequence
  1621.  
  1622.      For languages such as Pascal where strings are defined by single
  1623.      quotes and a literal single quote is specified by two single
  1624.      quotes ('It''s mine'), simply place the following definition:
  1625.  
  1626.           :string:
  1627.           '                        <== String & Character Delimiter
  1628.           '                        <== Escape Sequence
  1629.  
  1630.      For languages such as BASIC which do not allow you to place the
  1631.      string delimiter within the string, you would leave the second
  1632.      line blank.
  1633.  
  1634.  
  1635.  
  1636.                                   Page 26
  1637.                                    SOURCE
  1638.  
  1639.      You may declare up to five pairs of delimiters per language.  The
  1640.      full string definition for 'C' would be:
  1641.  
  1642.           :string:
  1643.           "
  1644.           \
  1645.           '
  1646.           \
  1647.  
  1648.      8.4.3  Blocks
  1649.  
  1650.      After specifying the string definition, you must define what
  1651.      commands make up blocks.  The keywords defined here are used with
  1652.      the 'b' option to allow block grouping to work.  The definition
  1653.      begins with the keyword ':block:'.  Following are two lines per
  1654.      block.  The first line is the begin block command and the second
  1655.      line is the end block command.  For 'C', this is easy because all
  1656.      blocks are marked the same.  Blocks begin with a left curly brace
  1657.      and end with a right curly brace.  The definition would be:
  1658.  
  1659.           :block:
  1660.           {
  1661.           }
  1662.  
  1663.      For languages like Pascal, you may have numerous block pairs. 
  1664.      Example:
  1665.  
  1666.           :block:
  1667.           begin
  1668.           end
  1669.           record
  1670.           end
  1671.           case
  1672.           end
  1673.           repeat
  1674.           until
  1675.  
  1676.      For most languages, the keyword used to define a block must be
  1677.      entered in its entirety.  You can't specify 
  1678.  
  1679.           beg
  1680.           ...
  1681.           end
  1682.  
  1683.      in Pascal for example.  You must enter the whole keyword.  A
  1684.      counter example to this is the dBase programming language.  dBase
  1685.      allows you to enter only the first four letters of each keyword. 
  1686.      A 'while' loop could be entered as:
  1687.  
  1688.           do while                           do whil
  1689.           ...                 or             ...
  1690.           enddo                              endd
  1691.  
  1692.      For SOURCE to work with a language such as this, you must specify
  1693.      the "part" or "partial" keyword after the "endlang" keyword at
  1694.  
  1695.                                   Page 27
  1696.                                    SOURCE
  1697.  
  1698.      the end of the language definition followed by the number of
  1699.      characters needed.  If SOURCE finds the 'part' keyword at the end
  1700.      of a definition, comment and block keywords entered in SOURCE.LNG
  1701.      for that language will be treated as the minimal text that must
  1702.      be entered to be a valid keyword in the program.  If the 'part'
  1703.      keyword is not specified, SOURCE will treat the comment and block
  1704.      keywords in SOURCE.LNG as the full keyword that must be found in
  1705.      the file being printed.
  1706.  
  1707.      8.4.4  Keywords
  1708.  
  1709.      After specifying the block definition, you must define those
  1710.      keywords that you would like highlighted when the 'k' option is
  1711.      active.  The definition begins with the keyword ':keyword:' and
  1712.      is followed by one keyword per line.  The keywords may have
  1713.      spaces in them.  The words may be entered in any order.  You may
  1714.      enter any words you like.  The idea is to highlight reserved
  1715.      words so you can pick out variables and function names easier. 
  1716.      If you have certain functions or other words you would like
  1717.      highlighted, simply add them to the list.  A partial list for 'C'
  1718.      would be:
  1719.  
  1720.           :keyword:
  1721.           auto
  1722.           break
  1723.           case
  1724.           char
  1725.           const
  1726.           continue
  1727.           . . .
  1728.  
  1729.      If the language is case dependant, ensure the keywords are
  1730.      entered in the proper case.  If case independant, the entered
  1731.      case is irrelevant.  If the language supports partial keyword
  1732.      matching (like dBASE), you must enter the shortest portion of the
  1733.      keyword that the language recognizes just as you did for the
  1734.      'block' section.  SOURCE will highlight the entire keyword found
  1735.      in the program.  For example, if you have the keyword 'endt'
  1736.      (short for 'endtext' in dBASE) in the language definition, and
  1737.      SOURCE finds the 'endtext' in the program, the entire 'endtext'
  1738.      will be highlighted.
  1739.  
  1740.      It is important that the keywords entered only contain those
  1741.      characters entered on the second line of language definition.  If
  1742.      other characters are used, the keyword may not be highlighted
  1743.      properly.  You may define up to 400 keywords per language.
  1744.  
  1745.      8.4.5  Complete Definition
  1746.  
  1747.      Now that you have seen each part of the definition, here is a
  1748.      full definition as it would appear in SOURCE.LNG for 'C'.
  1749.  
  1750.           beginlang C .c .h
  1751.           abcdefghijklmnopqrstuvwxyz0123456789_   <== Valid characters
  1752.           :comment:
  1753.  
  1754.                                   Page 28
  1755.                                    SOURCE
  1756.  
  1757.           /*
  1758.           */
  1759.           0                        <== Any column
  1760.           :string:
  1761.           "
  1762.           \
  1763.           '
  1764.           \
  1765.           :block:
  1766.           {
  1767.           }
  1768.           :keyword:
  1769.           auto
  1770.           break
  1771.           case
  1772.           char
  1773.           const
  1774.           continue
  1775.           . . .          <== There are more, but you get the point
  1776.           endlang case
  1777.  
  1778.      For dBase, the full definition would be:
  1779.  
  1780.           beginlang dbase .prg
  1781.           :comment:
  1782.           *
  1783.                                    <== Comments end with end-of-line
  1784.           0                        <== Begin in any column
  1785.           &&
  1786.                                    <== Comments end with end-of-line
  1787.           0
  1788.           note
  1789.                                    <== Comments end with end-of-line
  1790.           0
  1791.           :string:
  1792.           "
  1793.                                    <== No double quotes in strings
  1794.           :block:
  1795.           do case
  1796.           endc                     <== Minimum required
  1797.           do whil                  <== Minimum required
  1798.           endd                     <== Minimum required
  1799.           if
  1800.           endi                     <== Minimum required
  1801.           text
  1802.           endt                     <== Minimum required
  1803.           :keyword:
  1804.           acce
  1805.           addi
  1806.           alia
  1807.           all
  1808.           all like
  1809.           appe
  1810.           appe from
  1811.           . . .          <== There are more, but you get the point
  1812.  
  1813.                                   Page 29
  1814.                                    SOURCE
  1815.  
  1816.           endlang part 4
  1817.  
  1818.      8.5  General Points
  1819.  
  1820.      Some points to keep in mind when defining a language.  If you
  1821.      have more than one language with the same extension, SOURCE will
  1822.      choose the first.  To override this, you can use the 'x' option
  1823.      on the command line to explicitly choose the language you really
  1824.      need.  
  1825.  
  1826.      While defining a comment or a block, you may not define two or
  1827.      more pairs that begin with the same keyword, regardless of the
  1828.      ending keyword.  However, you may define any number of pairs that
  1829.      have the same ending keyword as long as the beginning keywords
  1830.      are unique.  This should never be a problem because two blocks
  1831.      with the same beginning keyword would lead to a rather ambiguous
  1832.      syntax.
  1833.  
  1834.      When defining blocks for the language, be careful with statements
  1835.      using variable syntax.  A good example is the 'IF' statement in
  1836.      some BASICs.  The syntax can be:
  1837.  
  1838.      1)   IF condition THEN statement [ELSE statement]
  1839.  
  1840.           or
  1841.  
  1842.      2)   IF condition THEN
  1843.             statements
  1844.           [ELSE
  1845.             statements]
  1846.           ENDIF
  1847.  
  1848.      DO NOT specify in your block definitions 'IF' - 'ENDIF' because
  1849.      if SOURCE encounters the first syntax, the line will never
  1850.      terminate because it will not find the 'ENDIF'.  Unfortunately,
  1851.      there is no solution to this.  The only downside is that you will
  1852.      not get trace lines for your IF statements.  If you know for a
  1853.      fact that you did not use the first syntax, then go ahead and
  1854.      specify the 'IF' - 'ENDIF' block.
  1855.  
  1856.      9    Network Support
  1857.  
  1858.      SOURCE currently has limited network support.  The support
  1859.      offered at this time allows you to define an environment variable
  1860.      called "USER".  SOURCE will determine the value of "USER" and
  1861.      load the named configuration, from SOURCE.CFG, of the same name. 
  1862.      This configuration option will be used as the default set of
  1863.      options instead of "Default".
  1864.  
  1865.      This setup allows SOURCE to be installed on a network server. 
  1866.      Each user would add a line like:
  1867.  
  1868.      set USER=<name>
  1869.  
  1870.  
  1871.  
  1872.                                   Page 30
  1873.                                    SOURCE
  1874.  
  1875.      to their "autoexec.bat" file.  The <name> would be a unique
  1876.      identifier for that person.  This could be a last name or
  1877.      initials.  The SOURCE.CFG file in the SOURCE directory would
  1878.      contain a named configuration for each user on the network.
  1879.  
  1880.      Care must be taken to limit write access to the common SOURCE.CFG
  1881.      file.  You may wish to allow only the network supervisor to
  1882.      update this file to prevent problems with each user adding their
  1883.      options.  Data will get lost if two people try editing at the
  1884.      same time.
  1885.  
  1886.      If SOURCE cannot find a named configuration with the same name as
  1887.      the value of "USER", SOURCE will fall back on the "Default" named
  1888.      configuration.
  1889.  
  1890.      Having the environment variable defined is slightly different
  1891.      from using the '-u <name>' command line option.  When using the
  1892.      environment variable, the matching named configuration is used in
  1893.      place of the default named configuration.  When using the 'u'
  1894.      option, the matching named configuration is loaded in addition to
  1895.      the default named configuration.
  1896.  
  1897.      10   Definition of Shareware
  1898.  
  1899.      Shareware distribution gives users a chance to try software
  1900.      before buying it.  If you try a Shareware program and continue
  1901.      using it, you are expected to register.
  1902.  
  1903.      Copyright laws apply to both Shareware and commercial software,
  1904.      and the copyright holder retains all rights, with a few specific
  1905.      exceptions as stated below.  Shareware authors are accomplished
  1906.      programmers, just like commercial authors, and the programs are
  1907.      of comparable quality.  (In both cases, there are good programs
  1908.      and bad ones!)  The main difference is in the method of
  1909.      distribution.  The author specifically grants the right to copy
  1910.      and distribute the software, either to all and sundry or to a
  1911.      specific group.  For example, some authors require written
  1912.      permission before a commercial disk vendor may copy their
  1913.      Shareware.
  1914.  
  1915.      Shareware is a distribution method, not a type of software.  You
  1916.      should find software that suits your needs and pocketbook,
  1917.      whether it's commercial or Shareware.  The Shareware system makes
  1918.      fitting your needs easier, because you can try before you buy.  
  1919.      And because the overhead is low, prices are low also.  Shareware
  1920.      has the ultimate money-back guarantee -- if you don't use the
  1921.      product, you don't pay for it.
  1922.  
  1923.      11   Disclaimer - Agreement For Trying SOURCE
  1924.  
  1925.      Users of SOURCE must accept this disclaimer of warranty:
  1926.  
  1927.           "SOURCE is supplied as is.  The author disclaims all
  1928.           warranties, expressed or implied, including, without
  1929.           limitation, the warranties of merchantability and of
  1930.  
  1931.                                   Page 31
  1932.                                    SOURCE
  1933.  
  1934.           fitness for any purpose.  The author assumes no
  1935.           liability for damages, direct or consequential, which
  1936.           may result from the use of SOURCE."
  1937.  
  1938.      SOURCE is a "shareware program" and is provided at no charge to
  1939.      the user for evaluation.  Feel free to share it with your
  1940.      friends, but please do not give it away altered or as part of
  1941.      another system.  The essence of "user-supported" software is to
  1942.      provide personal computer users with quality software without
  1943.      high prices, and yet to provide incentive for programmers to
  1944.      continue to develop new products.  If you find this program
  1945.      useful and find that you are using SOURCE and continue to use
  1946.      SOURCE after a reasonable trial period, you must make a
  1947.      registration payment to Rick Maddy.  
  1948.  
  1949.      The registration fee will license one copy for use on any one
  1950.      computer at any one time.  You must treat this software just like
  1951.      a book.  An example is that this software may be used by any
  1952.      number of people and may be freely moved from one computer
  1953.      location to another, so long as there is no possibility of it
  1954.      being used at one location while it's being used at another. 
  1955.      Just as a book cannot be read by two different persons at the
  1956.      same time.  Site-License arrangements may be made by contacting
  1957.      Rick Maddy.
  1958.  
  1959.      You are encouraged to pass a copy of SOURCE along to your friends
  1960.      for evaluation.  Please encourage them to register their copy if
  1961.      they find that they can use it.  All registered users will
  1962.      receive a copy of the latest version of SOURCE in your name,
  1963.      printed documentation, a quick reference card, upgrade notices
  1964.      and discounts, and customer support.
  1965.  
  1966.      12   Registering
  1967.  
  1968.      You may use SOURCE for a free 30 day trial period.  If you
  1969.      continue to use SOURCE after the 30 day trial period, you are
  1970.      required to register your copy of SOURCE.
  1971.  
  1972.      When you register SOURCE you will be sent a disk with the latest
  1973.      version of SOURCE in your name, printed documentation, a quick
  1974.      reference card, upgrade notices and discounts, and customer
  1975.      support.  The cost of registration is $20.00.
  1976.  
  1977.      You can order directly from Rick Maddy by completing the
  1978.      registration form and mailing it and a check to:
  1979.  
  1980.                          Rick Maddy
  1981.                          7111 Kurth Lane
  1982.                          Seabrook, MD 20706
  1983.  
  1984.      The registration form is at the end of this document and in a
  1985.      separate file called register.txt.
  1986.  
  1987.  
  1988.  
  1989.  
  1990.                                   Page 32
  1991.                                    SOURCE
  1992.  
  1993.      If you have any questions or comments, feel free to call Rick
  1994.      Maddy at (301) 794-8466 or leave a mail message on Compuserve at
  1995.      76460,1601.
  1996.  
  1997.      13   Future Enhancements
  1998.  
  1999.      I have a few ideas for making SOURCE an even better utility. 
  2000.      Here is a brief list:
  2001.  
  2002.           - Full screen interface to replace command line.
  2003.           - Full screen programs for editing printer, language, and
  2004.             configuration files.
  2005.           - Windows 3.1 version.
  2006.           - Optional log file of all printed files.
  2007.           - Expanded file selection (i.e. date range).
  2008.           - Print files in sorted order by name, size, date, etc.
  2009.           - Expanded network/multi-user support.
  2010.  
  2011.      I am open to any comments or suggestions for improvements or
  2012.      additions to SOURCE.  Please drop me a line.
  2013.  
  2014.      14   Acknowledgements
  2015.  
  2016.      I would like to thank the following people for all there help in
  2017.      finishing this program:
  2018.  
  2019.           - Scott Sidel for his help with making this program easier
  2020.             to use and writing this documentation.
  2021.  
  2022.           - Robert Harvey and William Moussiaux for beta testing
  2023.             SOURCE.
  2024.  
  2025.           - All the kind people who answered my questions about OS/2
  2026.             on Compuserve.
  2027.  
  2028.  
  2029.  
  2030.  
  2031.  
  2032.  
  2033.  
  2034.  
  2035.  
  2036.  
  2037.  
  2038.  
  2039.  
  2040.  
  2041.  
  2042.  
  2043.  
  2044.  
  2045.  
  2046.  
  2047.  
  2048.  
  2049.                                   Page 33
  2050.                             SOURCE REGISTRATION
  2051.  
  2052.      Remit to:                From:
  2053.  
  2054.      Rick Maddy               Name:__________________________________
  2055.      7111 Kurth Lane          Company:_______________________________
  2056.      Seabrook, Md 20706       Street:________________________________
  2057.      (301) 794-8466           City:__________________________________
  2058.                               State/Zip:_____________________________
  2059.      Compuserve Id:           Phone:_________________________________
  2060.      76460, 1601
  2061.                               Name to register in:
  2062.                               (Up to 40 characters)
  2063.  
  2064.                               _______________________________________
  2065.  
  2066.  
  2067.      Qty:                          Unit Price     Total:
  2068.  
  2069.      ____ SOURCE Software          $20.00         ________
  2070.  
  2071.  
  2072.      Specify Disk Size:
  2073.  
  2074.      _____  5 1/4"       _____  3 1/2"
  2075.  
  2076.  
  2077.      Current Version of Source:______________________________________
  2078.  
  2079.